@turf/helpers

What is @turf/helpers?

The @turf/helpers package is part of the Turf.js library, which is a modular geospatial engine written in JavaScript. It provides functions to create various simple geometrical features such as points, lines, and polygons, and to manipulate these geometries in various ways. This package is particularly useful for developers working with geographic information systems (GIS) and spatial analysis in web applications.

What are @turf/helpers's main functionalities?

Creating Points

This function creates a GeoJSON Point feature using the provided coordinates. It is useful for representing locations on a map.

const point = turf.point([5, 10]);

Creating LineStrings

This function creates a GeoJSON LineString feature from an array of positions. It is useful for mapping routes or paths.

const line = turf.lineString([[5, 10], [20, 40]]);

Creating Polygons

This function creates a GeoJSON Polygon feature from an array of linear rings. It is used to represent areas such as city boundaries or lakes.

const polygon = turf.polygon([[[5, 10], [20, 40], [40, 0], [5, 10]]]);

Other packages similar to @turf/helpers

leaflet

Leaflet is a leading open-source JavaScript library for mobile-friendly interactive maps. While Leaflet itself focuses more on map interactions and overlays, it can be used in conjunction with other tools for creating and manipulating geographic data, similar to @turf/helpers.

openlayers

OpenLayers is another powerful open-source JavaScript library that handles various map-related tasks. It provides more comprehensive features for handling complex spatial operations compared to @turf/helpers, which is more focused on creating and manipulating simple geometrical features.

README

@turf/helpers

feature

Wraps a GeoJSON Geometry in a GeoJSON Feature.

Parameters

• geometry Geometry input geometry
• properties [Object] an Object of key-value pairs to add as properties (optional, default {})
• bbox [Array<number>] BBox [west, south, east, north]
• id [(string | number)] Identifier

Examples

var geometry = {
  "type": "Point",
  "coordinates": [110, 50]
};

var feature = turf.feature(geometry);

//=feature

Returns Feature a GeoJSON Feature

geometry

Creates a GeoJSON Geometry from a Geometry string type & coordinates. For GeometryCollection type use helpers.geometryCollection

Parameters

• type string Geometry Type
• coordinates Array<number> Coordinates
• bbox [Array<number>] BBox [west, south, east, north]

Examples

var type = 'Point';
var coordinates = [110, 50];

var geometry = turf.geometry(type, coordinates);

//=geometry

Returns Geometry a GeoJSON Geometry

point

Takes coordinates and properties (optional) and returns a new Point feature.

Parameters

• coordinates Array<number> longitude, latitude position (each in decimal degrees)
• properties [Object] an Object of key-value pairs to add as properties (optional, default {})
• bbox [Array<number>] BBox [west, south, east, north]
• id [(string | number)] Identifier

Examples

var point = turf.point([-75.343, 39.984]);

//=point

Returns Feature<Point> a Point feature

polygon

Takes an array of LinearRings and optionally an Object with properties and returns a Polygon feature.

Parameters

• coordinates Array<Array<Array<number>>> an array of LinearRings
• properties [Object] an Object of key-value pairs to add as properties (optional, default {})
• bbox [Array<number>] BBox [west, south, east, north]
• id [(string | number)] Identifier

Examples

var polygon = turf.polygon([[
  [-2.275543, 53.464547],
  [-2.275543, 53.489271],
  [-2.215118, 53.489271],
  [-2.215118, 53.464547],
  [-2.275543, 53.464547]
]], { name: 'poly1', population: 400});

//=polygon

• Throws Error throw an error if a LinearRing of the polygon has too few positions or if a LinearRing of the Polygon does not have matching Positions at the beginning & end.

Returns Feature<Polygon> a Polygon feature

lineString

Creates a LineString based on a coordinate array. Properties can be added optionally.

Parameters

• coordinates Array<Array<number>> an array of Positions
• properties [Object] an Object of key-value pairs to add as properties (optional, default {})
• bbox [Array<number>] BBox [west, south, east, north]
• id [(string | number)] Identifier

Examples

var linestring1 = turf.lineString([
  [-21.964416, 64.148203],
  [-21.956176, 64.141316],
  [-21.93901, 64.135924],
  [-21.927337, 64.136673]
]);
var linestring2 = turf.lineString([
  [-21.929054, 64.127985],
  [-21.912918, 64.134726],
  [-21.916007, 64.141016],
  [-21.930084, 64.14446]
], {name: 'line 1', distance: 145});

//=linestring1

//=linestring2

• Throws Error if no coordinates are passed

Returns Feature<LineString> a LineString feature

featureCollection

Takes one or more Features and creates a FeatureCollection.

Parameters

• features Array<Feature> input features
• bbox [Array<number>] BBox [west, south, east, north]
• id [(string | number)] Identifier

Examples

var features = [
 turf.point([-75.343, 39.984], {name: 'Location A'}),
 turf.point([-75.833, 39.284], {name: 'Location B'}),
 turf.point([-75.534, 39.123], {name: 'Location C'})
];

var collection = turf.featureCollection(features);

//=collection

Returns FeatureCollection a FeatureCollection of input features

multiLineString

Creates a Feature<MultiLineString> based on a coordinate array. Properties can be added optionally.

Parameters

• coordinates Array<Array<Array<number>>> an array of LineStrings
• properties [Object] an Object of key-value pairs to add as properties (optional, default {})
• bbox [Array<number>] BBox [west, south, east, north]
• id [(string | number)] Identifier

Examples

var multiLine = turf.multiLineString([[[0,0],[10,10]]]);

//=multiLine

• Throws Error if no coordinates are passed

Returns Feature<MultiLineString> a MultiLineString feature

multiPoint

Creates a Feature<MultiPoint> based on a coordinate array. Properties can be added optionally.

Parameters

• coordinates Array<Array<number>> an array of Positions
• properties [Object] an Object of key-value pairs to add as properties (optional, default {})
• bbox [Array<number>] BBox [west, south, east, north]
• id [(string | number)] Identifier

Examples

var multiPt = turf.multiPoint([[0,0],[10,10]]);

//=multiPt

• Throws Error if no coordinates are passed

Returns Feature<MultiPoint> a MultiPoint feature

multiPolygon

Creates a Feature<MultiPolygon> based on a coordinate array. Properties can be added optionally.

Parameters

• coordinates Array<Array<Array<Array<number>>>> an array of Polygons
• properties [Object] an Object of key-value pairs to add as properties (optional, default {})
• bbox [Array<number>] BBox [west, south, east, north]
• id [(string | number)] Identifier

Examples

var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]);

//=multiPoly

• Throws Error if no coordinates are passed

Returns Feature<MultiPolygon> a multipolygon feature

geometryCollection

Creates a Feature<GeometryCollection> based on a coordinate array. Properties can be added optionally.

Parameters

• geometries Array<Geometry> an array of GeoJSON Geometries
• properties [Object] an Object of key-value pairs to add as properties (optional, default {})
• bbox [Array<number>] BBox [west, south, east, north]
• id [(string | number)] Identifier

Examples

var pt = {
    "type": "Point",
      "coordinates": [100, 0]
    };
var line = {
    "type": "LineString",
    "coordinates": [ [101, 0], [102, 1] ]
  };
var collection = turf.geometryCollection([pt, line]);

//=collection

Returns Feature<GeometryCollection> a GeoJSON GeometryCollection Feature

round

Round number to precision

Parameters

• num number Number
• precision [number] Precision (optional, default 0)

Examples

turf.round(120.4321)
//=120

turf.round(120.4321, 2)
//=120.43

Returns number rounded number

radiansToDistance

Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet

Parameters

• radians number in radians across the sphere
• units [string] can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default kilometers)

Returns number distance

distanceToRadians

Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet

Parameters

• distance number in real units
• units [string] can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default kilometers)

Returns number radians

distanceToDegrees

Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet

Parameters

• distance number in real units
• units [string] can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default kilometers)

Returns number degrees

bearingToAngle

Converts any bearing angle from the north line direction (positive clockwise) and returns an angle between 0-360 degrees (positive clockwise), 0 being the north line

Parameters

• bearing number angle, between -180 and +180 degrees

Returns number angle between 0 and 360 degrees

radians2degrees

Converts an angle in radians to degrees

Parameters

• radians number angle in radians

Returns number degrees between 0 and 360 degrees

degrees2radians

Converts an angle in degrees to radians

Parameters

• degrees number angle between 0 and 360 degrees

Returns number angle in radians

convertDistance

Converts a distance to the requested unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet

Parameters

• distance number to be converted
• originalUnit string of the distance
• finalUnit [string] returned unit (optional, default kilometers)

Returns number the converted distance

convertArea

Converts a area to the requested unit. Valid units: kilometers, kilometres, meters, metres, centimetres, millimeter, acre, mile, yard, foot, inch

Parameters

• area number to be converted
• originalUnit [string] of the distance (optional, default meters)
• finalUnit [string] returned unit (optional, default kilometers)

Returns number the converted distance

isNumber

isNumber

Parameters

• num Any Number to validate

Examples

turf.isNumber(123)
//=true
turf.isNumber('foo')
//=false

Returns boolean true/false

---

This module is part of the Turfjs project, an open source module collection dedicated to geographic algorithms. It is maintained in the Turfjs/turf repository, where you can create PRs and issues.

Installation

Install this module individually:

$ npm install @turf/helpers

Or install the Turf module that includes it as a function:

$ npm install @turf/turf